Quarto for scientific writing: Reports, presentations, and even blogs & websites

Available at lcgodoy.me/slides/2024-lm/

Lucas da Cunha Godoy

EEB Department, UCSC

2024-11-04

Introduction

Scientific writing

  • Equations

  • Figures

  • Cross-references

  • Formatting

Word processor programs

  • The most popular writing programs are Microsoft Word (first released in 1983 as Multi-Tool Word) and the much newer Google Docs (2006) 1.

  • They are often referred to “What You See Is What You Get” (WYSIWYG) text processors.

  • Common tasks in scientific writing can take more time than they should when working with WYSIWYG.

Markup languages: A different paradigm

  • A markup language uses special codes to structure and format text.

  • One of the first markup languages is TeX (released in 1978). LaTeX is the most popular TeX-based language.

  • A popular (and newer) markup language is Markdown. Some Markdown extensions incorporate LaTeX features.

Literate programming

Warning

Not an exhaustive list.

Literate programming appeal

  • Content driven writing

  • Consistency and automation

  • Portability and longevity

  • Version control

What is Quarto?

Quarto: Next-Gen R Markdown

  • Quarto is a literate programming considered that superseded R Markdown.

  • It is a standalone (sort of) piece of software instead of a package.

  • Support for several languages: R, python, julia, javascript.

  • It aims at making reproducible research and publications the norm rather than the exception.

What do I need to write Quarto documents?

  • A compatible IDE 1:
    • VS Code
    • Jupyter
    • RStudio
    • Neovim
    • Sublime
    • Emacs
  • Alternative: A code/text editor and a terminal

  • The Get Started page provides instructions on how to Download/Install Quarto and examples with different IDEs.

Who is Quarto for and why should I use it?

  • Everyone that wants to produce beautiful documents and is not afraid of some code would benefit from using Quarto.

  • Scientists that write documents with many equations.

  • Reproducible documents.

  • Learn one tool that can be used for writing reports, books, presentations, and even websites.

Quarto documents structure

Basic structure

---
title: "My Quarto Document"
format:
  html:
    code-fold: true
jupyter: python3
---

## My title

### My subtitle

Writing in _italic_, **bold**. A [hyperlink to quarto
website](https://quarto.org)

* list item 1

  * list sub-item

* list item 2
  • YAML 1 header (optional but recommended)
    • Controls the “engine”, the type of the output file, and some output specific parameters
  • Markdown
    • Code based headers, text formatting, and cross-references
  • Code to be executed.

Equations

  • Equations can be rendered inline and on their own line. See the example below.
The density of a normally distributed random variable $X$ with mean $\mu$ and
variance $\sigma^2$ is 
$$
f(x) = \frac{1}{\sqrt{2 \pi \sigma^2}} \exp \left \{ \frac{1}{2 \sigma^2} (x -
\mu)^2 \right \}
$$

The density of a normally distributed random variable \(X\) with mean \(\mu\) and variance \(\sigma^2\) is \[ f(x) = \frac{1}{\sqrt{2 \pi \sigma^2}} \exp \left \{ \frac{1}{2 \sigma^2} (x - \mu)^2 \right \} \]

Figures

Code

![This is Cacau. Cacau in Portuguese means cocoa.](<adress-of-my-figure>)

For more details about figures, see this link

Result

This is Cacau. Cacau in Portuguese means cocoa.

Sub-Figures

Code

::: {#fig-both layout-ncol=2}

![This is Cacau. Cacau in Portuguese means cocoa.](<adress-of-my-figure>)

![This is Kalu. She is not happy I'm using pictures of dogs.](<adress-of-my-figure>)

My Caption!
:::

For more details about figures, see this link

Result

This is Cacau. Cacau in Portuguese means cocoa.

This is Kalu. She is not happy I’m using pictures of dogs.
Figure 1: My Caption!

Code execution

#| label: fig-peng
#| fig-cap: "A scatterplot."

library(ggplot2)
library(palmerpenguins)
library(dplyr)

data(package = "palmerpenguins")

ggplot(data = penguins,
       aes(x = flipper_length_mm,
           y = bill_length_mm,
           color = species)) +
  geom_point() +
  theme_bw() +
  labs(x = "Flipper length (mm)",
       y = "Bill length (mm)",
       color = "Species") +
  theme(legend.position = "top")

Code execution

Figure 2: A scatterplot.

Tables

  • There are many options/configurations for tables available.

  • One can simply generate tables from code.

#| label: tbl-peng
#| tbl-cap: "Penguins again."

penguins |>
  count(species) |>
  mutate(proportion = 100 * n / sum(n)) |>
  arrange(desc(n)) |>
  knitr::kable(digits = 1)
Table 1: Penguins again.
species n proportion
Adelie 152 44.2
Gentoo 124 36.0
Chinstrap 68 19.8

Cross-referencing

  • In Quarto we can easily cross-reference Sections, Equations, Figures, and Tables – we will refer to these categories as “entities”.

  • To enable this feature, each entity must have a label (unique identifier) and, for figures and tables, a caption. See Table 2.

Table 2: Mapping entities to the structure of their labels.
Entity Label
Section sec-
Table tbl-
Figure fig-
Equation eq-

Citations

  • Quarto does not have a Zotero plugin (you can find tutorials on how to use them together)

  • Before Zotero, there was BIBTeX!

  • BIBTeX is both a bibliographic database file format and a software for processing references (citations).

  • References are listed in a .bib file (show how to obtain bibfiles).

@article{matthews2019craft,
  title =        {Craft beautiful equations in {W}ord with {LaTeX}},
  author =       {Matthews, David and others},
  journal =      {Nature},
  volume =       570,
  number =       7760,
  pages =        {263--264},
  year =         2019,
  publisher =    {Nature}
}

Showcase example

One source many outputs

  • I used the same code to generate a presentation, a pdf file, and an html report.

  • In the next few sessions, I will show the source for these files and their respective outputs.

  • I also used this example to showcase how Quarto’s cross-referencing works.

Conclusion

Overview

  • Quarto can enhance your productivity and the reproducibility of your research material

  • As any code-related resource, the learning curve may be steep

  • Once you learn, you can easily recycle and modify documents according to changes in your data

  • It is also trivial to change templates.

  • Although Quarto is open-source, its developer (and maintainer) is a company (posit)

Resources

  • Quarto website provides many resources.

  • The gallery has many examples categorized by their type (i.e., presentations, reports, etc)

  • A curated list of resources and features is available at awesome-quarto on GitHub.

  • I have a blog post on how to create your personal website using Quarto. The post also shows how to host it on GitHub Pages.

References

Leisch, F. (2002), “Sweave: Dynamic generation of statistical reports using literate data analysis,” in COMPSTAT: Proceedings in computational statistics, Springer, pp. 575–580.
Schulte, E., Davison, D., Dye, T., and Dominik, C. (2012), “A multi-language computing environment for literate programming and reproducible research,” Journal of Statistical Software, 46, 1–24.
Xie, Y., Allaire, J. J., and Grolemund, G. (2018), R markdown: The definitive guide, Boca Raton, Florida: Chapman; Hall/CRC.